feat(sdk-logs): Add Logger Configurator API & Trace-based + Min-Severity Filtering #5991

JacksonWeber · 2025-10-07T02:12:29Z

Which problem is this PR solving?

This pull request introduces advanced logger configuration capabilities to the OpenTelemetry JS SDK Logs package. The main feature is the new LoggerConfigurator API, which allows users to filter logs by minimum severity, trace sampling status, and to configure loggers individually using pattern matching. These changes improve flexibility and control over log processing and exporting.

Logger configuration and filtering features

Added the LoggerConfigurator API, enabling users to define per-logger configuration for severity filtering, trace-based filtering, and logger disabling, with pattern matching for logger names. (experimental/packages/sdk-logs/src/config/LoggerConfigurators.ts, experimental/packages/sdk-logs/src/types.ts, experimental/packages/sdk-logs/src/LoggerProvider.ts, experimental/packages/sdk-logs/src/internal/LoggerProviderSharedState.ts) [1] [2] [3] [4] [5] [6]
Updated the Logger class to apply minimum severity and trace-based filtering before emitting log records, dropping logs that don't meet the configured criteria. (experimental/packages/sdk-logs/src/Logger.ts) [1] [2]

Documentation and API updates

Expanded the README.md with detailed documentation and usage examples for the new logger configuration features, including severity and trace-based filtering and per-logger configuration patterns. (experimental/packages/sdk-logs/README.md)
Updated type exports and API surface to include LoggerConfig, LoggerConfigurator, and createLoggerConfigurator. (experimental/packages/sdk-logs/src/index.ts) [1] [2]

Changelog and test updates

Added a changelog entry for the new loggerConfigurator feature. (experimental/CHANGELOG.md)
Updated and expanded tests to cover the new logger configuration and filtering logic. (experimental/packages/sdk-logs/test/common/Logger.test.ts)

Type of change

Please delete options that are not relevant.

New feature (non-breaking change which adds functionality)

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

Unit tests for each type of filtering added

Checklist:

Followed the style guidelines of this project
Unit tests have been added
Documentation has been updated

codecov · 2025-10-07T02:15:37Z

Codecov Report

❌ Patch coverage is 96.55172% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.40%. Comparing base (167185a) to head (d6cf204).

Files with missing lines	Patch %	Lines
...ackages/sdk-logs/src/config/LoggerConfigurators.ts	95.45%	1 Missing ⚠️
...sdk-logs/src/internal/LoggerProviderSharedState.ts	94.11%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5991   +/-   ##
=======================================
  Coverage   95.40%   95.40%           
=======================================
  Files         317      319    +2     
  Lines        9439     9494   +55     
  Branches     2187     2203   +16     
=======================================
+ Hits         9005     9058   +53     
- Misses        434      436    +2

Files with missing lines	Coverage Δ
experimental/packages/sdk-logs/src/Logger.ts	`100.00% <100.00%> (ø)`
...perimental/packages/sdk-logs/src/LoggerProvider.ts	`100.00% <100.00%> (ø)`
...perimental/packages/sdk-logs/src/internal/utils.ts	`100.00% <100.00%> (ø)`
...ackages/sdk-logs/src/config/LoggerConfigurators.ts	`95.45% <95.45%> (ø)`
...sdk-logs/src/internal/LoggerProviderSharedState.ts	`96.66% <94.11%> (-3.34%)`	⬇️

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

pichlermarc

Specification: https://github.com/open-telemetry/opentelemetry-specification/blame/f31acdf68b1c886269ab39011a338a8d72dbebea/specification/logs/sdk.md#L102-L133

@JacksonWeber - please also mark all features that are marked as in-development in the spec as @experimental in the TSdoc. This way we can avoid blocking https://github.com/open-telemetry/opentelemetry-js/milestone/19

JacksonWeber · 2025-10-07T18:05:53Z

Specification: https://github.com/open-telemetry/opentelemetry-specification/blame/f31acdf68b1c886269ab39011a338a8d72dbebea/specification/logs/sdk.md#L102-L133

@JacksonWeber - please also mark all features that are marked as in-development in the spec as @experimental in the TSdoc. This way we can avoid blocking https://github.com/open-telemetry/opentelemetry-js/milestone/19

Experimental features have been marked as such. Thanks for the feedback!

outdated

pichlermarc

Hmm, overall I'm a bit confused by this feature - the spec for it seems still a bit vague and seems to duplicate functionality from existing features. 🤔 That's not this PR's issue, I feel like it's a symptom of a spec that's not quite where we'd need it to be yet.

I suppose the value proposition for having a LoggerConfigurator is to save on allocations in the pipeline - which is important for a hot path like this. (Q: @JacksonWeber is this the motivation for working on this feature?) If that's not the goal, then we could accomplish the same thing today in the LogRecordProcessor.

Though it seems to me that the optimizing LogRecordImpl to avoid expensive operations until it's properties are first accessed, and then applying filtering in the LogRecordProcessor may be a better way to go about it without adding additional concept to the public API.

The Go SIG seems to have a similar stance: open-telemetry/opentelemetry-specification#4644

pichlermarc · 2025-10-22T08:51:08Z

experimental/packages/sdk-logs/src/Logger.ts

+    // Get logger configuration
+    const loggerConfig = this._sharedState.getLoggerConfig(
+      this.instrumentationScope
+    );


Given that emit is a hot-path, I think we should optimize here wherever possible.

One thing I noticed is that the way it's implemented right now is:

we call getLoggerConfig()

if it has already cached something for this Logger, it will always return that initial config

dynamic updates are therefore not possible

Do we need the map lookup or should we just cache it in the logger? 🤔

The primary motivation for this feature work is just to get an implementation of trace-based log sampling and minimum severity-based log sampling implemented in a way that's easy for users to enable as part of the configuration of their LoggerProvider.

Thanks for the link to the issue in the Go repo, I'm happy to refactor this PR to avoid the creation/usage of the LoggerConfigurator and just implement these two filtering strategies in the LogRecordProcessor.

@pichlermarc the PR has been updated to just add a new logRecordProcessor that handles both types of filtering. Please review when you have a chance.

@pichlermarc per our conversation in the JS SIG today I've reverted the changes here back to following the spec (creating the logger configurator).

thanks, sorry for the churn. 🙇‍♂️

I think my original concern is still there. Since we don't support re-configuration we may want to cache the config in the logger instead of doing the map lookup on each logger.emit() for performance gains. Especially since we have do do a string allocation to compute the key for the map lookup.

@pichlermarc comments are addressed, let me know if the PR looks good now.

pichlermarc · 2025-11-26T16:00:19Z

experimental/packages/sdk-logs/src/config/LoggerConfigurators.ts

+/**
+ * Configuration for a specific logger pattern
+ */
+export interface LoggerPattern {
+  /**
+   * The logger name or pattern to match.
+   * Use '*' for wildcard matching.
+   */
+  pattern: string;
+
+  /**
+   * The configuration to apply to matching loggers.
+   * Partial config is allowed; unspecified properties will use defaults.
+   *
+   * @experimental This feature is in development as per the OpenTelemetry specification.
+   */
+  config: LoggerConfig;
+}


I think we'd need an experimental annotation on all of these (the type and properties)

Good catch, updated this.

pichlermarc · 2025-11-26T16:11:44Z

experimental/packages/sdk-logs/src/internal/LoggerProviderSharedState.ts

+  private _getScopeKey(scope: InstrumentationScope): string {
+    return `${scope.name}@${scope.version || ''}:${scope.schemaUrl || ''}`;
  }


suggestion: let's make this a utility function since we don't need to access this here.

Makes sense, I've added a utils folder in the sdk-logs to house this new util function.

pichlermarc · 2025-11-26T16:15:56Z

experimental/packages/sdk-logs/src/Logger.ts

+    // Get logger configuration
+    const loggerConfig = this._sharedState.getLoggerConfig(
+      this.instrumentationScope
+    );


thanks, sorry for the churn. 🙇‍♂️

I think my original concern is still there. Since we don't support re-configuration we may want to cache the config in the logger instead of doing the map lookup on each logger.emit() for performance gains. Especially since we have do do a string allocation to compute the key for the map lookup.

pichlermarc · 2025-11-26T16:20:24Z

experimental/packages/sdk-logs/src/types.ts

+/**
+ * A LoggerConfig defines various configurable aspects of a Logger's behavior.
+ */
+export interface LoggerConfig {
+  /**
+   * A boolean indication of whether the logger is enabled.
+   * If a Logger is disabled, it behaves equivalently to a No-op Logger.
+   * Defaults to false (loggers are enabled by default).
+   */
+  disabled?: boolean;


I think these two also need an experimental annotation.

Added, thanks for the catch!

experimental/packages/sdk-logs/README.md

JacksonWeber added 2 commits October 6, 2025 16:28

Add loggerConfigurator and tests.

ff06c8a

Update README.md

cfd6b7f

JacksonWeber requested a review from a team as a code owner October 7, 2025 02:12

Update CHANGELOG.md

5ac7921

pichlermarc previously requested changes Oct 7, 2025

View reviewed changes

JacksonWeber added the pkg:sdk-logs label Oct 7, 2025

JacksonWeber added 2 commits October 7, 2025 10:29

Fix lint & add @experimental tags.

c407f31

Update README.md

8e25840

JacksonWeber requested a review from pichlermarc October 7, 2025 18:05

pichlermarc added the spec-feature This is a request to implement a new feature which is already specified by the OTel specification label Oct 8, 2025

pichlermarc reviewed Oct 22, 2025

View reviewed changes

JacksonWeber changed the title ~~feat(sdk-logs): Add loggerConfigurator~~ feat(sdk-logs): Add FilteringLogRecordProcessor Oct 23, 2025

JacksonWeber requested a review from pichlermarc October 23, 2025 18:23

JacksonWeber force-pushed the jacksonweber/logger-sampling branch from 12fb209 to 8e25840 Compare November 13, 2025 01:36

JacksonWeber added 3 commits November 12, 2025 17:39

Merge branch 'main' into jacksonweber/logger-sampling

319ec0a

Update Logger.test.ts

681fc14

Update Logger.test.ts

c822cc3

JacksonWeber changed the title ~~feat(sdk-logs): Add FilteringLogRecordProcessor~~ feat(sdk-logs): Add Logger Configurator API & Trace-based + Min-Severity Filtering Nov 13, 2025

JacksonWeber added 3 commits November 13, 2025 13:05

Merge branch 'main' into jacksonweber/logger-sampling

0dc7941

Merge branch 'main' into jacksonweber/logger-sampling

2029cc7

Merge branch 'main' into jacksonweber/logger-sampling

93553aa

JacksonWeber mentioned this pull request Nov 18, 2025

Allow filtering logs being sent to AppInsights by log level Azure/azure-sdk-for-js#36456

Open

pichlermarc self-assigned this Nov 19, 2025

JacksonWeber added 4 commits November 19, 2025 14:17

Merge branch 'main' into jacksonweber/logger-sampling

38bebd8

Merge branch 'main' into jacksonweber/logger-sampling

8cc9360

Merge branch 'main' into jacksonweber/logger-sampling

6e9324b

Merge branch 'main' into jacksonweber/logger-sampling

3cf69a5

Merge branch 'main' into jacksonweber/logger-sampling

bf23a55

pichlermarc reviewed Nov 26, 2025

View reviewed changes

JacksonWeber added 5 commits November 26, 2025 13:38

Add support for caching the config in the logger.

2e9091c

Add further experimental annotations.

8b5850e

Create getInstrumentationScopeKey utils function.

756bee4

Add further experimental flags.

13e96a7

Fix lint.

d6cf204

JacksonWeber requested a review from pichlermarc November 26, 2025 22:04

feat(sdk-logs): Add Logger Configurator API & Trace-based + Min-Severity Filtering #5991

Are you sure you want to change the base?

feat(sdk-logs): Add Logger Configurator API & Trace-based + Min-Severity Filtering #5991

Conversation

JacksonWeber commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Which problem is this PR solving?

Logger configuration and filtering features

Documentation and API updates

Changelog and test updates

Type of change

How Has This Been Tested?

Checklist:

Uh oh!

codecov bot commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

pichlermarc left a comment

Choose a reason for hiding this comment

Uh oh!

JacksonWeber commented Oct 7, 2025

Uh oh!

pichlermarc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pichlermarc Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pichlermarc Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JacksonWeber commented Oct 7, 2025 •

edited

Loading

codecov bot commented Oct 7, 2025 •

edited

Loading

pichlermarc Nov 26, 2025 •

edited

Loading

pichlermarc Nov 26, 2025 •

edited

Loading